home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_200 / 285_01 / bisoninf.1 < prev    next >
Text File  |  1990-07-08  |  51KB  |  1,228 lines
  1. Info file bison.info, produced by Makeinfo, -*- Text -*- from input
  2. file bison.texinfo.
  3.  
  4. This file documents the Bison parser generator.
  5.  
  6. Copyright (C) 1988 Free Software Foundation, Inc.
  7.  
  8. Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12. Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided also
  14. that the sections entitled ``Bison General Public License'' and
  15. ``Conditions for Using Bison'' are included exactly as in the
  16. original, and provided that the entire resulting derived work is
  17. distributed under the terms of a permission notice identical to this
  18. one.
  19.  
  20. Permission is granted to copy and distribute translations of this
  21. manual into another language, under the above conditions for modified
  22. versions, except that the text of the translations of the sections
  23. entitled ``Bison General Public License'' and ``Conditions for Using
  24. Bison'' must be approved for accuracy by the Foundation.
  25.  
  26.  
  27.  
  28. File: bison.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
  29.  
  30. * Menu:
  31.  
  32. * Introduction::
  33. * Conditions::
  34. * Copying::           The Bison General Public License says
  35.                         how you can copy and share Bison
  36.  
  37. Tutorial sections:
  38. * Concepts::          Basic concepts for understanding Bison.
  39. * Examples::          Three simple explained examples of using Bison.
  40.  
  41. Reference sections:
  42. * Grammar File::      Writing Bison declarations and rules.
  43. * Interface::         C-language interface to the parser function `yyparse'.
  44. * Algorithm::         How the Bison parser works at run-time.
  45. * Error Recovery::    Writing rules for error recovery.
  46. * Debugging::         Debugging Bison parsers that parse wrong.
  47. * Invocation::        How to run Bison (to produce the parser source file).
  48. * Table of Symbols::  All the keywords of the Bison language are explained.
  49. * Glossary::          Basic concepts are explained.
  50. * Index::             Cross-references to the text.
  51.  
  52.  
  53.  
  54. File: bison.info,  Node: Introduction,  Next: Conditions,  Prev: Top,  Up: Top
  55.  
  56. Introduction
  57. ************
  58.  
  59. "Bison" is a general-purpose parser generator which converts a
  60. grammar description into a C program to parse that grammar.  Once you
  61. are proficient with Bison, you may use it to develop a wide range of
  62. language parsers, from those used in simple desk calculators to
  63. complex programming languages.
  64.  
  65. Bison is upward compatible with Yacc: all properly-written Yacc
  66. grammars ought to work with Bison with no change.  Anyone familiar
  67. with Yacc should be able to use Bison with little trouble.  You need
  68. to be fluent in C programming in order to use Bison or to understand
  69. this manual.
  70.  
  71. We begin with tutorial chapters that explain the basic concepts of
  72. using Bison and show three explained examples, each building on the
  73. last.  If you don't know Bison or Yacc, start by reading these
  74. chapters.  Reference chapters follow which describe specific aspects
  75. of Bison in detail.
  76.  
  77. Bison was basically written by Robert Corbett, and made
  78. Yacc-compatible by Richard Stallman.
  79.  
  80.  
  81.  
  82. File: bison.info,  Node: Conditions,  Next: Copying,  Prev: Introduction,  Up: Top
  83.  
  84. Conditions for Using Bison
  85. **************************
  86.  
  87. Bison grammars can be used only in programs that are free software. 
  88. This is in contrast to what happens with the GNU C compiler and the
  89. other GNU programming tools.
  90.  
  91. The reason Bison is special is that the output of the Bison
  92. utility--the Bison parser file--contains a verbatim copy of a sizable
  93. piece of Bison, which is the code for the `yyparse' function.  (The
  94. actions from your grammar are inserted into this function at one
  95. point, but the rest of the function is not changed.)
  96.  
  97. As a result, the Bison parser file is covered by the same copying
  98. conditions that cover Bison itself and the rest of the GNU system:
  99. any program containing it has to be distributed under the standard
  100. GNU copying conditions.
  101.  
  102. Occasionally people who would like to use Bison to develop
  103. proprietary programs complain about this.
  104.  
  105. We don't particularly sympathize with their complaints.  The purpose
  106. of the GNU project is to promote the right to share software and the
  107. practice of sharing software; it is a means of changing society.  The
  108. people who complain are planning to be uncooperative toward the rest
  109. of the world; why should they deserve our help in doing so?
  110.  
  111. However, it's possible that a change in these conditions might
  112. encourage computer companies to use and distribute the GNU system. 
  113. If so, then we might decide to change the terms on `yyparse' as a
  114. matter of the strategy of promoting the right to share.  Such a
  115. change would be irrevocable.  Since we stand by the copying
  116. permissions we have announced, we cannot withdraw them once given.
  117.  
  118. We mustn't make an irrevocable change hastily.  We have to wait until
  119. there is a complete GNU system and there has been time to learn how
  120. this issue affects its reception.
  121.  
  122.  
  123.  
  124. File: bison.info,  Node: Copying,  Next: Concepts,  Prev: Conditions,  Up: Top
  125.  
  126. Bison General Public License
  127. ****************************
  128.  
  129.                         (Clarified 11 Feb 1988)
  130.  
  131. The license agreements of most software companies keep you at the
  132. mercy of those companies.  By contrast, our general public license is
  133. intended to give everyone the right to share Bison.  To make sure
  134. that you get the rights we want you to have, we need to make
  135. restrictions that forbid anyone to deny you these rights or to ask
  136. you to surrender the rights.  Hence this license agreement.
  137.  
  138. Specifically, we want to make sure that you have the right to give
  139. away copies of Bison, that you receive source code or else can get it
  140. if you want it, that you can change Bison or use pieces of it in new
  141. free programs, and that you know you can do these things.
  142.  
  143. To make sure that everyone has such rights, we have to forbid you to
  144. deprive anyone else of these rights.  For example, if you distribute
  145. copies of Bison, you must give the recipients all the rights that you
  146. have.  You must make sure that they, too, receive or can get the
  147. source code.  And you must tell them their rights.
  148.  
  149. Also, for our own protection, we must make certain that everyone
  150. finds out that there is no warranty for Bison.  If Bison is modified
  151. by someone else and passed on, we want its recipients to know that
  152. what they have is not what we distributed, so that any problems
  153. introduced by others will not reflect on our reputation.
  154.  
  155. Therefore we (Richard Stallman and the Free Software Foundation,
  156. Inc.) make the following terms which say what you must do to be
  157. allowed to distribute or change Bison.
  158.  
  159. Copying Policies
  160. ================
  161.  
  162.   1. You may copy and distribute verbatim copies of Bison source code
  163.      as you receive it, in any medium, provided that you
  164.      conspicuously and appropriately publish on each copy a valid
  165.      copyright notice ``Copyright (C) 1988 Free Software Foundation,
  166.      Inc.'' (or with whatever year is appropriate); keep intact the
  167.      notices on all files that refer to this License Agreement and to
  168.      the absence of any warranty; and give any other recipients of
  169.      the Bison program a copy of this License Agreement along with
  170.      the program.  You may charge a distribution fee for the physical
  171.      act of transferring a copy.
  172.  
  173.   2. You may modify your copy or copies of Bison or any portion of
  174.      it, and copy and distribute such modifications under the terms
  175.      of Paragraph 1 above, provided that you also do the following:
  176.  
  177.         * cause the modified files to carry prominent notices stating
  178.           that you changed the files and the date of any change; and
  179.  
  180.         * cause the whole of any work that you distribute or publish,
  181.           that in whole or in part contains or is a derivative of
  182.           Bison or any part thereof, to be licensed at no charge to
  183.           all third parties on terms identical to those contained in
  184.           this License Agreement (except that you may choo